Flamingo Plus/4 emulator for the Amiga External video driver documentation version 2.0 Friday 21.07.2000 Intro ----- As became an "industry standard" Flamingo have external driver for video. That is a must because of the mess of different Amiga video drivers, cards and other trouble makers, and because of my limited possibilities and abilities. I am not perfect, God knows, even you can write a much faster video driver than mine. To build a video driver for Flamingo is as easy as a pie. You have to obey some rules anyway, those are included in this text. Before you start coding anything please (PLEASE!) read this doc carefully! Format ------ As usual too external video drivers are executables, and loaded by LoadSeg, when needed. If your version is working on the PowerPC processor, you have use WarpUP, as FlamingoPPC works on this kernel. (Mixed binary preferred here!) To allow this you have to start with these lines (in that case, when anybody start it without Flamingo): moveq.l #0,d0 rts Then you have to continue with a simple pattern for identify: dc.b 'FLAMINGOXVD' Next byte is for identify video-driver version level. This should be for now: dc.b '2' That was all about identify. Verison level will be raised if any changes should become in driver format later. Then a little table coming up: dc.l Name_of_video_driver ; -> pointer dc.l Author_of_video_driver ; -> pointer dc.w Version ; -> not pointer, but the number dc.w Revision ; -> not pointer, but the number Name and Author strings should be zero terminated. And finally the table of pointers to the functions: dc.l drv_Init dc.l drv_Done dc.l drv_Configure dc.l drv_OpenScreen dc.l drv_CloseScreen dc.l drv_Refresh dc.l drv_RefreshPPC Functions --------- At first: keep in mind code must be reentant. No global variables, memory array etc... Of course you have to hold your data somewhere, and this would be a memory segment allocated by your driver, and it will be given as parameter for every function of yours. (Let's call handler.) This handler should be given back by drv_Init_driver function. Flamingo will never change this piece of memory. (Of course not, it knows nothing about it, even not the length.) You can mess up all registers Flamingo saves his regs before your routine will be called. All subroutines called by a JSR, so all have to end with RTS. (BLR for PPC Refresh.) Okay, let's go on with the functions: * drv_Init * Inputs: A0 - pointer to library bases A1 - public screen (eg. Workbench) Outputs: D0 - handler D1 - ptr to message You can do anything in this function, initialisations, open libraries etc. As input the routine will get a structure of longwords: dc.l graphics_library_base dc.l dos_library_base dc.l intuition_library_base dc.l gadtools_library_base dc.l asl_library_base dc.l powerpc_library_base Do not open provided libraries use these bases! PowerPC.library base could be zero, that might mean no PPC available. Don't forget handle this. (Eg. checking at the start, and cancel the init.) As output give back any number in D0 except zero (0). This will be your handler, you may ignore it, if you need no room to store something (I can hardly believe). Zero output means your driver was failed to initialize itself. (Missing driver, library etc.) In this case you can send a pointer to an error message string in D1. It will be displayed in some way. (If D0 not zero D1 will be ignored.) * drv_Done * Inputs: A0 - handler Deallocate all system resources you have ever allocated. Do not call drv_CloseScreen from this routine, it will be called before! Don't forget deallocate all memory, even used by handler! * drv_Configure * Inputs: A0 - handler You can open an interface, if your driver needs any configuration. All library bases (gadtools too) was given in drv_Init, do not reopen these! The other parts of Flamingo are hanging while your configuration is running. Important! If this field in the structure contains zero, then configure button will be disabled in Flamingo's GUI. (Please put zero here, if you have nothing to configure.) * drv_OpenScreen * Inputs: A0 - handler A1 - screen_params Output: D0 - valid IDCMP port address D1 - ptr to message D2 - ptr to allocated chunky buffer D3 - modulo for the chunky buffer (LONG) Open your screen by this routine. Screen_params is a structure to dc.w xsize dc.w ysize dc.l palette ;ptr to the palette xsize is screen width and always an even multiple of 16, ysize is screen height, palette a pointer to an array of RGB values on 8 bits per gun each (R1,G1,B1,R2,G2,B2,...) contains 121 colors. About screen format can be found more in refresh part. If your routine was not able to open its screen, then send back 0 in D0, and you can also send some zero terminated string in D1 as an error message. (drv_Done called in this case too!) If open was successful send a valid IDCMP port address in D0, D1 will be ingored. The only IDCMP required by Flamingo is IDCMP_RAWKEY, other messages will be discarded. Don't forget to allocate chunky buffer for the emulated screen! Give back this address in D2. (Size is xsize*ysize in bytes.) There is an easy way on graphcards doing double buffered chunky screens, by allocating both buffer and changing displayed at drv_Refresh. (Find out more at there.) I added modulo for the chunky screen, as it might be useful for native chunky displays. * drv_CloseScreen * Input: A0 - handler Close your screen by this routine. (Or hide, if you prefer, but watch out on hide, drv_OpenScreen can be recall after drv_CloseScreen! And don't forget deallocate your screen on drv_Done...) * drv_Refresh * Input: A0 - handler Output: D0 - (next) chunky screen This routine changed since the 2nd version of the XVD format. The pointer can b be 0, if your driver uses only the PowerPC routine and vice versa. Watch out! If both pointer non NULL, both will be called! Here you have to refresh your screen. If your driver is a graphcard driver which can set up chunky 8 bit screen, you have to do almost nothing in this routine, but for an AGA driver this is the most hardest part. After your screen was opened, your palette was loaded, you have to convert 8 bit chunky data to your screen. In the emulator screen colors between 0-127 had been used. You can see: only 7 bit is enough. Chunky format: one pixel is one byte, 0th. bit is LSB, 6th. bit is MSB and 7th. is always 0 (hopefully, you can depend on this). After finishing the conversion (or anything you do), give back the (next) address of chunky screen in D0. (You can do easly double buffering on graphcards.) If you use the same chunky buffer again, then give back that address. I see no reason of an MMU based driver, emulator uses line-based screen emulation, and it refreshes all lines on screen at this time. BTW a delta buffer would be grateful for slow conversion. * drv_RefreshPPC * Input: A0 - handler Output: D0 - (next) chunky screen Just like the one before, except this routine must be completely on the PowerPC part. It will be called without context-switches, thus speeds up the PPC version. (In the 68k verison will do context switch of course... :) It should be working exactly the same way as the drv_Refresh does. The driver can be in two separated executables, but I see no reason why would anybody choose this way. WarpUP's mixed binary would be better. Do not use asynchrone routines here! Contact ------- Any questions and comments are welcome: racs@fs2.bdtf.hu Thank you for supporting Flamingo project! Álmos Rajnai